Context v2: name the binding, show the measurement, stop the false URL - #21
Merged
Merged
Conversation
From a design partner consuming a live bound cell. Four document changes,
one breaking, plus the OpenAPI surface that let two of them go unnoticed.
- declared.exports[].binding {source, object, connection}, present iff
`query` is null. A bound export's target existed only in docs prose and
`data.channels`' operator hints, so writing a query against a cell that
serves no rows meant reading English. Values are verbatim cell.yaml,
never profile-resolved: `table` is env-expandable and `Declared` is
hashed into interface_digest, so a resolved value would fold the
environment into the digest.
- observed.source_check.exports[route] {check, grain, rows,
distinct_grain}. verify::grain_counts computed the numbers behind
`grain_verified`, compared them, and discarded them. Persisted through
.cell/source_check.json under the record's existing digest+profile gate,
visibility-filtered on the way to the wire. A grainless export
contributes no entry — no check ran on it.
- MeshExport.bound, so an agent routing off the manifest stops picking an
export that 404s. The emitter accepts datamk_context 1 or 2.
- declared.docs[].path -> source_path, which is why datamk_context is 2.
A cell.yaml-relative path named `path` in a JSON document served over
HTTP reads as a relative URL and 404s — the same false affordance
already corrected for `route`.
/context's 200 had no schema at all, so nothing said include= content
lands at a top-level key named for the section rather than inside
`included` (which holds section names). It has one now, pinned to
ContextDocument's keys by a test. Data path items carry x-datamk-version
and x-datamk-contract, previously prose inside `summary`.
Declined, with reasoning in the ADR: a cell-level semver (no cell version
exists; it would drift from the per-export semvers) and a structured
`caveats` array (free-text rule + unenforced severity is prose in a JSON
wrapper, drifting like source_descriptions already does). The hazard
caveats aimed at — two USD columns that must not be subtracted — stays
open; the only fix that isn't docs-in-JSON is a typed column property the
engine can verify.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
From a design partner consuming a live bound cell. Four document changes, one breaking, plus the OpenAPI surface that let two of them go unnoticed.
queryis null. A bound export's target existed only in docs prose anddata.channels' operator hints, so writing a query against a cell that serves no rows meant reading English. Values are verbatim cell.yaml, never profile-resolved:tableis env-expandable andDeclaredis hashed into interface_digest, so a resolved value would fold the environment into the digest.grain_verified, compared them, and discarded them. Persisted through .cell/source_check.json under the record's existing digest+profile gate, visibility-filtered on the way to the wire. A grainless export contributes no entry — no check ran on it.pathin a JSON document served over HTTP reads as a relative URL and 404s — the same false affordance already corrected forroute./context's 200 had no schema at all, so nothing said include= content lands at a top-level key named for the section rather than inside
included(which holds section names). It has one now, pinned to ContextDocument's keys by a test. Data path items carry x-datamk-version and x-datamk-contract, previously prose insidesummary.Declined, with reasoning in the ADR: a cell-level semver (no cell version exists; it would drift from the per-export semvers) and a structured
caveatsarray (free-text rule + unenforced severity is prose in a JSON wrapper, drifting like source_descriptions already does). The hazard caveats aimed at — two USD columns that must not be subtracted — stays open; the only fix that isn't docs-in-JSON is a typed column property the engine can verify.